/**
 * Licensed under the GNU LESSER GENERAL PUBLIC LICENSE, version 2.1, dated February 1999.
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the latest version of the GNU Lesser General
 * Public License as published by the Free Software Foundation;
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program (LICENSE.txt); if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 */
package org.jamwiki.parser.jflex;

import java.util.Map;
import org.jamwiki.parser.ParserException;

/**
 * Interface for custom parser tags.  Note that as of JAMWiki 1.1 this
 * interface is still under development, so anyone interested in building
 * their own custom tags should be aware that this is NOT a stable API.
 *
 * See the <code>/WEB-INF/classes/jamwiki-configuration-1.3.xml</code> for
 * configuration - any custom parser tag must currently be identified in
 * that file in order for it to be used by the parser.
 */
public interface JFlexCustomTagItem {

	/**
	 * Initialize the tag with any key-value params passed in from the configuration.
	 * This method will be called immediately after the tag is instantiated.
	 */
	public void initParams(Map<String, String> initParams);

	/**
	 * Return the tag name.  If the tag is "<custom>" then the tag name is "custom".
	 */
	public String getTagName();

	/**
	 * Set the tag name.  If the tag is "<custom>" then the tag name is "custom".
	 */
	public void setTagName(String tagName);

	/**
	 * Parse a custom tag of the form <custom attribute="value">content</custom>
	 * into wiki text.  Note that the custom tag parser runs after the template
	 * parser, so wiki text generated by this method cannot include templates,
	 * signatures, or other wiki text that would have already been parsed earlier
	 * in the parser cycle.
	 *
	 * @param lexer A reference to the current lexer instance.
	 * @param attributes A map of key-value pairs representing all of the tag's
	 *  attributes.  Note that if the same key is specified more than once then
	 *  only the final occurrence will be included in the attribute map.
	 * @param content The tag's content, or <code>null</code> if the tag has
	 *  no body content.
	 * @return Wiki text representing the parsed tag output.  This output may be
	 *  further parsed into HTML by later parser iterations.  Note that if the
	 *  custom tag returns HTML then that HTML may not render as expected
	 *  depending on whether or not the wiki is configured to allow HTML, so
	 *  output should always be as wiki text.
	 * @throws ParserException Thrown if any error occurs during parsing.
	 */
	public String parse(JFlexLexer lexer, Map<String, String> attributes, String content) throws ParserException;
}
